Simplify doc meta mode by notriddle · Pull Request #159473 · rust-lang/rust

notriddle · 2026-07-17T22:35:07Z

Get rid of the mode where you can finalize the CCI and generate more docs at the same time. It isn't used in Cargo, and probably won't be used elsewhere?

rustbot · 2026-07-17T22:35:12Z

r? @folkertdev

rustbot has assigned @folkertdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: compiler
compiler expanded to 74 candidates
Random selection from 17 candidates

notriddle · 2026-07-17T22:36:25Z

r? @camelid

rustbot · 2026-07-17T22:36:29Z

camelid is currently at their maximum review capacity.
They may take a while to respond.

Since we're getting rid of the ability to do finalize and document at the same time, we can't actually do this in the rustdoc-html test build system and need to do it this way instead.

Co-authored-by: Noah Lev <37223377+camelid@users.noreply.github.com>

rustbot · 2026-07-26T02:19:44Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

camelid

Looks good overall, but I'd like to avoid the dummy crate and TyCtxt, and some of the tests seem to be translated wrong from the original files.

View changes since this review

camelid · 2026-07-27T17:49:47Z

+    let krate = ast::Crate {
+        attrs: Default::default(),
+        items: Default::default(),
+        spans: Default::default(),
+        id: ast::DUMMY_NODE_ID,
+        is_placeholder: false,
+    };


I don't love that we're creating a dummy crate here just to get a TyCtxt. It seems like we only use the TyCtxt to get the Sess. So I don't think you actually need to do this. interface::Compiler already has a Sess on it.

I've removed the synthetic crate, but not the synthetic InputStr.

camelid · 2026-07-27T17:56:50Z

+            let config = core::create_config(
+                Input::Str {
+                    name: rustc_span::FileName::Custom(String::new()),
+                    input: String::new(),
+                },
+                options,
+                &render_options,
+            );
            return wrap_return(
                dcx,
-                rustc_span::create_session_globals_then(options.edition, &[], None, || {
-                    run_merge_finalize(render_options)
+                interface::run_compiler(config, |compiler| {
+                    run_merge_finalize(render_options, compiler)


Ditto here, but getting rid of the fake Input::Str is harder, and this seems less bad than making a fake crate and TyCtxt. So fine to just leave it.

camelid · 2026-07-27T18:13:27Z

+        .arg(format!("--read-doc-meta-dir={}", parts_out_dir.display()))
+        .arg("--enable-index-page")
+        .run();
+    output.assert_stderr_not_contains("error: the compiler unexpectedly panicked. this is a bug.");


nit: Is this necessary? Shouldn't the run-make test fail automatically if one of its subprocesses ICEs? (I'm not super familiar with run-make, so I might be wrong about this.)

I just checked, and you're right.

rust/src/tools/run-make-support/src/command.rs

Lines 232 to 240 in d3ea035

pub fn run(&mut self) -> CompletedProcess {

let output = self.command_output();

if !output.status().success() {

handle_failed_output(&self, output, panic::Location::caller().line());

} else {

verbose_print_command(self, &output);

}

output

}

Apparently, when a run-make command exits with a non-zero exit code, this thing will fail the test.

rust/src/tools/run-make-support/src/util.rs

Lines 31 to 43 in d3ea035

pub(crate) fn handle_failed_output(

cmd: &Command,

output: CompletedProcess,

caller_line_number: u32,

) -> ! {

if output.status().success() {

eprintln!("command unexpectedly succeeded at line {caller_line_number}");

} else {

eprintln!("command failed at line {caller_line_number}");

}

print_command_output(cmd, &output);

std::process::exit(1)

}

camelid · 2026-07-27T18:15:38Z

+
+fn main() {
+    let merged_dir = path("merged");
+    let parts_out_dir = path("parts");


Is this just not used at all?

It's not. I've removed it.

camelid · 2026-07-27T18:19:59Z

+        .library_search_path(cwd())
+        .out_dir(&out_dir)
+        .arg("-Zunstable-options")
+        .arg("--write-doc-meta-dir=parts-wrong")


I don't understand why this is parts-wrong -- if they all use the same name, there's nothing wrong about it. I think this might have been lost in translation from the original test.

There's no --read-doc-meta-dir, and the sierra.rs tests all verify that the shared resources aren't generated.

I've added a comment, and renamed the dir parts-unused, to clarify this.

rustbot · 2026-07-27T18:22:36Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

weihanglo · 2026-07-29T04:36:19Z

-If this parameter is supplied but `--read-doc-meta-dir` isn't, it runs in *intermediate mode*:
-some pages may be written to the output dir, but there is a lot of functionality that won't work
-until rustdoc is run in *finalize mode*.
+When `--write-doc-meta-dir` is supplied, rustdoc will write the crate's shared metadata to


Probably not the right question for this PR, and I haven't read the implementation here, though I am curious:

How does this interact with --out-dir. I guess --out-dir is ignored here?

How does this interact with all those --emit files (w/ or w/o --out-dir? Where will those files be emitted?

View changes since the review

Context: I'd like to pass --emit=dep-info without specifying the full (absolute) path for those dep-info files. Because of this issue #159743 we cannot specify full path, and currently blocks rust-lang/cargo#17020.

(That said, it is a very Cargo specific issue I feel like)

The --out-dir is still used as the path for --emit files. --write-doc-meta-dir doesn't pay attention to --out-dir.

I see. So eventually if individual rustdoc doesn't need to emit html contents, cargo then can use --emit to control dep-info emission location exclusively. Thanks!

camelid · 2026-07-29T18:31:07Z

We're also missing the root-level help.html and settings.html files in the finalize step.

notriddle · 2026-07-30T03:15:18Z

Good catch! settings.html and help.html are moved, so they get generated at finalize now.

camelid

Thanks! r=me with comments addressed. Or feel free to just merge and then fix in a later PR since this is already a big improvement.

Also, could you rename the title and edit the PR description since the scope has changed and grown a bit?

View changes since this review

camelid · 2026-07-31T20:19:51Z

+            }),
+            &style_files,
+        );
+        let mut file = try_err!(File::create_buffered(&settings_file), &settings_file);


Hmm I think it would actually be more efficient not to use a buffer since we're writing the whole thing in one go. We can just use std::fs::write probably. Ditto with the other write below.

camelid · 2026-07-31T20:29:14Z

 //@ has index.html
 //@ has index.html '//h1' 'List of all crates'
 //@ has index.html '//ul[@class="all-items"]//a[@href="quebec/index.html"]' 'quebec'
 //@ has index.html '//ul[@class="all-items"]//a[@href="sierra/index.html"]' 'sierra'
 //@ has index.html '//ul[@class="all-items"]//a[@href="tango/index.html"]' 'tango'
+//@ has help.html
+//@ has settings.html


I was going to ask for tests for this, but you were two steps ahead. :)

camelid · 2026-07-31T20:38:48Z

        let mut root_path = self.dst.to_str().expect("invalid path").to_owned();
        if !root_path.ends_with('/') {
            root_path.push('/');
        }


AFAICT this is all actually dead code.

camelid · 2026-07-31T20:38:56Z

+        let mut root_path = dst.to_str().expect("invalid path").to_owned();
+        if !root_path.ends_with('/') {
+            root_path.push('/');
+        }


camelid · 2026-07-31T20:42:51Z

+            logo: String::new(),
+            favicon: String::new(),


Seems like these (and scrape_examples_extension) should be filled in with real values.

camelid · 2026-07-31T21:07:45Z

Have we specified the behavior of rustdoc when two different invocations use the same --write-doc-meta-dir folder?

rustbot assigned folkertdev Jul 17, 2026

rustbot assigned camelid and unassigned folkertdev Jul 17, 2026

notriddle mentioned this pull request Jul 17, 2026

Stabilize rustdoc --merge --parts-out-dir, and --include-parts-dir options #152902

Open

camelid reviewed Jul 23, 2026

View reviewed changes

camelid added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 23, 2026

fmease reviewed Jul 25, 2026

View reviewed changes

Comment thread tests/run-make/rustdoc/merge-cross-crate-info/kitchen-sink-separate-dirs/indigo.rs

notriddle and others added 9 commits July 25, 2026 19:06

rustdoc: fix --enable-index-page with finalize

91131bb

rustdoc: move CCI tests to run-make

a36c898

Since we're getting rid of the ability to do finalize and document at the same time, we can't actually do this in the rustdoc-html test build system and need to do it this way instead.

rustdoc: write rmake scripts to test CCI

6887d4d

Document the changed doc meta features

32f1625

Update src/doc/rustdoc/src/unstable-features.md

18d6ebf

Co-authored-by: Noah Lev <37223377+camelid@users.noreply.github.com>

Update src/doc/rustdoc/src/unstable-features.md

ac3994e

Co-authored-by: Noah Lev <37223377+camelid@users.noreply.github.com>

rustdoc: clean up unused @ build diectives

c352016

rustdoc: no --read-doc-meta-dir and --write-doc-meta-dir at once

e03942b

rustdoc: move CCI run-make tests into the directory

d0fec14

notriddle force-pushed the rename-parts-to-dep-meta branch from 9e2125b to d0fec14 Compare July 26, 2026 02:19

camelid added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 27, 2026

camelid requested changes Jul 27, 2026

View reviewed changes

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 27, 2026

rustdoc: stop constructing an unneeded synth Crate

9d136ed

This comment has been minimized.

Sign in to view

rustdoc: remove unused code from rmake tests

f73cd1e

notriddle force-pushed the rename-parts-to-dep-meta branch from c3d3011 to f73cd1e Compare July 28, 2026 04:05

GuillaumeGomez approved these changes Jul 28, 2026

View reviewed changes

weihanglo reviewed Jul 29, 2026

View reviewed changes

weihanglo mentioned this pull request Jul 29, 2026

fix: stabilize -Zrustdoc-depinfo rust-lang/cargo#17020

Open

This comment has been minimized.

Sign in to view

rustdoc: generate settings and help at finalize

5f940df

notriddle force-pushed the rename-parts-to-dep-meta branch from 23fae6c to 5f940df Compare July 30, 2026 05:57

camelid approved these changes Jul 31, 2026

View reviewed changes

	pub fn run(&mut self) -> CompletedProcess {
	let output = self.command_output();
	if !output.status().success() {
	handle_failed_output(&self, output, panic::Location::caller().line());
	} else {
	verbose_print_command(self, &output);
	}
	output
	}

	pub(crate) fn handle_failed_output(
	cmd: &Command,
	output: CompletedProcess,
	caller_line_number: u32,
	) -> ! {
	if output.status().success() {
	eprintln!("command unexpectedly succeeded at line {caller_line_number}");
	} else {
	eprintln!("command failed at line {caller_line_number}");
	}
	print_command_output(cmd, &output);
	std::process::exit(1)
	}

Uh oh!

Uh oh!

Conversation

notriddle commented Jul 17, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jul 17, 2026

Uh oh!

notriddle commented Jul 17, 2026

Uh oh!

rustbot commented Jul 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustbot commented Jul 26, 2026

Uh oh!

camelid left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camelid Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

notriddle Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustbot commented Jul 27, 2026

Uh oh!

This comment has been minimized.

weihanglo Jul 29, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camelid commented Jul 29, 2026

Uh oh!

notriddle commented Jul 30, 2026

Uh oh!

This comment has been minimized.

camelid left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camelid commented Jul 31, 2026

Uh oh!

notriddle commented Jul 17, 2026 •

edited by rustbot

Loading

camelid left a comment •

edited by rustbot

Loading

camelid Jul 27, 2026 •

edited

Loading

notriddle Jul 28, 2026 •

edited

Loading

weihanglo Jul 29, 2026 •

edited by rustbot

Loading

camelid left a comment •

edited by rustbot

Loading